home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-04
/
notes210.zip
/
FG-2-10.TXT
< prev
Wrap
Text File
|
1992-01-31
|
37KB
|
1,208 lines
Release Notes
Fastgraph (tm) v2.10
Fastgraph/Light (tm) v1.10
January 31, 1992
Ted Gruber Software
PO Box 13408
Las Vegas, NV 89112
(702) 735-1980 voice
(702) 735-4603 FAX
(702) 796-7134 BBS
72000,1642 CIS
Copyright (c) 1991,1992 Ted Gruber Software.
All Rights Reserved.
------------------------------------------------------------------------------
Introduction
------------------------------------------------------------------------------
Fastgraph 2.10 offers two new video modes, new routines, new utilities, and
optimizations and improvements to many existing routines. Some of the more
important new features are:
* Support for "Mode X" (320x240 256-color VGA graphics) and its
320x480 scan-doubled extension
* Video page resizing that allows smooth, flicker-free panning
* PCX display and creation functions
* Logical video pages in conventional, expanded, or extended memory
* An improved mode-specific bit map format in video modes 13 to 18
* Routines to read or write a block of video DAC registers
* Suspension and resumption of asynchronous music
* 43-line and 50-line text mode extensions
* Turbo Pascal and Power C support
* Updated User's Guide (now with an index) and Reference Manual
To illustrate the Fastgraph routines introduced in version 2.10, we've added
new example programs. The addition of the new examples has resulted in the
resequencing of some of the examples from previous versions of Fastgraph. The
correspondence between the old and new example numbers is:
FG 2.00/2.01 example numbers FG 2.10 example numbers
---------------------------- -----------------------
3-5 to 3-8 3-6 to 3-9
5-12 to 5-14 5-14 to 5-16
6-11 to 6-14 6-12 to 6-15
7-4 to 7-10 7-5 to 7-11
9-15 to 9-20 9-16 to 9-21
9-21 to 9-26 9-23 to 9-28
------------------------------------------------------------------------------
New video modes
------------------------------------------------------------------------------
Fastgraph 2.10 offers two new extended VGA graphics video modes, as summarized
in the following table:
Mode No. of Page Size Physical Virtual
Number Resolution Colors in Bytes Pages Pages
------ ---------- ------ --------- -------- -------
22 320 x 240 256/256K 76,800 3+ none
23 320 x 480 256/256K 153,600 1+ none
Mode 22 is the so-called "mode X" recently described by Michael Abrash in
Dr. Dobb's Journal. To our knowledge, Fastgraph is the first commercial
graphics library to support this video mode. Mode 22 is appealing because
it offers 256 colors, has a 1:1 aspect ratio (i.e., pixels are square), and
is very fast.
The "+" following the number of physical pages means there is an additional
partial video page available. In mode 22, there are three full physical
pages (numbered 0 to 2) plus one partial page of 80 pixel rows (page 3). In
mode 23, there is one full page (page 0) plus one partial page of 320 pixel
rows (page 1). You can safely use the partial pages as long as you don't
reference pixel rows beyond the last available row. Also, you cannot make
the partial page the visual page.
The size of hardware characters in modes 22 and 23 is 8 x 8. This means
there are 30 character rows in mode 22 and 60 rows in mode 23.
------------------------------------------------------------------------------
Logical pages
------------------------------------------------------------------------------
In addition to physical and virtual video pages, Fastgraph 2.10 includes
logical video pages. Logical pages can be created in any video mode and
can exist in conventional memory, expanded memory (EMS), or extended memory
(XMS). However, they are not as versatile as physical or virtual pages
because the only operations you can perform with logical pages are:
* Copy an entire physical or virtual page to a logical page
* Copy an entire logical page to a physical or virtual page
* Copy an entire logical page to another logical page
Three new functions (fg_alloccms, fg_allocems, and fg_allocxms) are provided
for creating logical pages in conventional memory, expanded memory, and
extended memory, respectively. The fg_freepage function has been modified
to release all three types of logical pages. Other new Fastgraph functions
that deal with logical pages are summarized in the following section.
------------------------------------------------------------------------------
New mode-specific bit map format for modes 13 to 18
------------------------------------------------------------------------------
The native EGA and VGA graphics modes (modes 13-18) now use a different format
for mode-specific bit maps. In previous versions of Fastgraph, you had to
call the fg_drwimage or fg_getimage routines once for each color in the image
in these video modes. This is no longer true because these routines allow
storage of all colors in a single bit map, just as the other video modes do.
The new bit map format is identical to that of mode 9 (see pages 127-129 in
the Fastgraph User's Guide). The old format is still supported (it was the
same as the mode-independent format in these video modes), but you must now
use fg_drawmap and fg_getmap instead of fg_drwimage and fg_getimage.
It is our policy to maintain downward compatibility between all versions of
Fastgraph. However, we feel the benefits offered by Fastgraph's new EGA and
VGA mode-specific bit map format far outweigh the fact that it is different
from eariler versions (especially since the fg_drawmap and fg_getmap functions
offer the same bit map format as the previous versions of fg_drwimage and
fg_getimage).
------------------------------------------------------------------------------
New functions
------------------------------------------------------------------------------
FG_ALLOCCMS
Prototype
int fg_alloccms (int page_number);
Description
The fg_alloccms routine creates a logical page in conventional memory.
The amount of memory required depends on the current video mode and
video buffer dimensions.
Parameters
page_number is the number by which the logical page will be referenced.
It must be between 1 and 63.
Return value
0 = logical page created in conventional memory
-2 = invalid page number
-3 = page already created, or page exists as a physical or virtual page
-4 = insufficient expanded memory to create the page
Restrictions
This routine has no effect if page_number references a physical or
virtual video page.
The only function you can perform with logical pages is copying one
entire page to another (with fg_copypage).
See also
fg_allocems, fg_allocxms, fg_copypage, fg_freepage
Examples
8-9
------------------------------------------------------------------------------
FG_ALLOCEMS
Prototype
int fg_allocems (int page_number);
Description
The fg_allocems routine creates a logical page in expanded memory (EMS).
The amount of memory required depends on the current video mode and
video buffer dimensions.
Parameters
page_number is the number by which the logical page will be referenced.
It must be between 1 and 63.
Return value
0 = logical page created in expanded memory
-1 = Expanded Memory Manager not initialized
-2 = invalid page number
-3 = page already created, or page exists as a physical or virtual page
-4 = insufficient expanded memory to create the page
Restrictions
This routine has no effect if page_number references a physical or
virtual video page.
Before using this routine, you must use the fg_initems routine to
initialize the Expanded Memory Manager.
The only function you can perform with EMS logical pages is copying one
entire page to another (with fg_copypage).
See also
fg_alloccms, fg_allocxms, fg_copypage, fg_freepage, fg_initems
Examples
8-9
------------------------------------------------------------------------------
FG_ALLOCXMS
Prototype
int fg_allocxms (int page_number);
Description
The fg_allocxms routine creates a logical page in extended memory (XMS).
The amount of memory required depends on the current video mode and
video buffer dimensions.
Parameters
page_number is the number by which the logical page will be referenced.
It must be between 1 and 63.
Return value
0 = logical page created in extended memory
-1 = XMS driver not present
-2 = invalid page number
-3 = page already created, or page exists as a physical or virtual page
-4 = insufficient extended memory to create the page
Restrictions
This routine has no effect if page_number references a physical or
virtual video page.
Before using this routine, you must use the fg_initxms routine to
initialize the XMS device driver.
The only function you can perform with XMS logical pages is copying one
entire page to another (with fg_copypage).
See also
fg_alloccms, fg_allocems, fg_copypage, fg_freepage, fg_initxms
Examples
8-9
------------------------------------------------------------------------------
FG_BOX
Prototype
void fg_box (int minx, int maxx, int miny, int maxy);
Description
The fg_box routine draws a hollow rectangle in screen space or character
space, with respect to the clipping region. The width of the rectangle's
edges is one pixel unless changed with the fg_boxdepth routine.
Parameters
minx is the x coordinate of the rectangle's left edge.
maxx is the x coordinate of the rectangle's right edge. It must be
greater than or equal to the value of minx.
miny is the y coordinate of the rectangle's top edge.
maxy is the y coordinate of the rectangle's bottom edge. It must be
greater than or equal to the value of miny.
Return value
none
Restrictions
This routine has no effect in text video modes
See also
fg_boxdepth, fg_rect
Examples
6-11, 11-7
------------------------------------------------------------------------------
FG_BOXDEPTH
Prototype
void fg_boxdepth (int xwidth, int ywidth);
Description
The fg_boxdepth routine defines the depth of rectangles drawn with the
fg_box routine. The fg_setmode routine initializes the box depth to one
pixel in each direction.
Parameters
xdepth is the width in pixels of the rectangle's left and right sides.
It must be greater than zero.
ydepth is the width in pixels of the rectangle's top and bottom sides.
It must be greater than zero.
Return value
none
Restrictions
none
See also
fg_box
Exmaples
6-11
------------------------------------------------------------------------------
FG_COPYPAGE
Prototype
void fg_copypage (int source_page, int dest_page);
Description
The fg_copypage routine transfers the contents of one video page to
another. The pages may be physical, virtual, or logical video pages.
The call
fg_copypage(source,dest);
is equivalent to
fg_transfer(0,fg_getmaxx(),0,fg_getmaxy(),0,fg_getmaxx(),source,dest);
Parameters
source_page is the source video page number. It must be between 0 and 63.
dest_page is the destination video page number. It must be between 0 and
63.
Return value
none
Restrictions
If source_page and dest_page both reference logical pages, the pages must
exist in the same type of memory. For example, you cannot copy a logical
page in extended memory to a logical page in conventional memory.
See also
fg_alloccms, fg_allocems, fg_allocxms, fg_initems, fg_initxms, fg_transfer
Examples
8-9, 9-22
------------------------------------------------------------------------------
FG_DISPPCX
Prototype
int fg_disppcx (char *filename, int flags);
Description
The fg_disppcx routine displays an image stored in a PCX file. The image
will be positioned such that its upper left corner is at the graphics
cursor position of the active video page.
Parameters
filename is the name of the PCX file. A device and path name may be
included as part of the file name. The file name must be terminated by
a null character (that is, a zero byte).
flags is a bit mask that controls how the image is displayed.
Bit 0
0 = use palette values stored in the PCX file
1 = use the current palette settings
Bits 1-15 are reserved for future use and should be zero.
Return value
0 = success
1 = file not found
2 = file is not a PCX file
Restrictions
PCX files are specific to certain video modes. The table below summarizes
the compatible video modes for PCX files.
If PCX file was You can display
created in mode it in these modes
--------------- -----------------
4 or 5 4 or 5
6 or 11 6, 11, 13 to 18
9 9
13 to 18 13 to 18
19 19 to 23
Displaying a PCX file at a lower resolution (for example, a 640x480 PCX
file at 320x200) will truncate the display on the right and on the bottom.
This effectively displays the upper left corner of the PCX file. If you
attempt to display a PCX file in an incompatible video mode, fg_disppcx
will still display something, but it will be garbled.
The fg_disppcx routine has no effect in text video modes or in the
Hercules low-resolution graphics mode.
See also
fg_dispfile, fg_makepcx
Examples
9-15
------------------------------------------------------------------------------
FG_GETATTR
Prototype
int fg_getattr (int row, int column);
Description
The fg_getattr routine returns the character attribute stored at the
specified position on the active video page.
Parameters
row is the row number of the character cell to examine, between 0 and
24 (unless you've called fg_setlines to increase the number of lines
per page).
column is the column number of the character cell to examine, between
0 and 39 for 40-column modes, or between 0 and 79 for 80-column modes.
Return value
The character attribute stored at the specified position.
Restrictions
This routine has no effect in graphics video modes.
See also
fg_getchar, fg_getimage
Examples
7-4
------------------------------------------------------------------------------
FG_GETCHAR
Prototype
int fg_getchar (int row, int column);
Description
The fg_getchar routine returns the character value stored at the specified
position on the active video page.
Parameters
row is the row number of the character cell to examine, between 0 and
24 (unless you've called fg_setlines to increase the number of lines
per page).
column is the column number of the character cell to examine, between
0 and 39 for 40-column modes, or between 0 and 79 for 80-column modes.
Return value
The character value stored at the specified position.
Restrictions
This routine has no effect in graphics video modes.
See also
fg_getattr, fg_getimage
Examples
7-4
------------------------------------------------------------------------------
FG_GETDACS
Prototype
void fg_getdacs (int start, int count, char *values);
Description
The fg_getdacs routine retrieves the red, green, and blue color components
of a contiguous block of video DAC registers. Each color component is a
value between 0 and 63; increasing values produce more intense colors.
Reading many DAC registers with fg_getdacs is considerably faster than
doing so individually with fg_getrgb.
Parameters
start is the starting video DAC register number, between 0 and 255.
count is the number of contiguous DAC registers to retrieve. If the
sum of start and count exceeds 255, the register numbers wrap around
and resume with register number 0.
values is the array that will receive the color components. The first
three bytes of this array receive the red, green, and blue components
for DAC register start, the next three bytes receive the components for
register start+1, and so forth. The size of the values array must be at
least 3*count bytes.
Return value
none
Restrictions
This routine has no effect in text video modes, or in any graphics video
mode numbered 16 or below (because these video modes do not use DAC
registers).
See also
fg_getrgb, fg_setdacs, fg_setrgb
Examples
5-12
------------------------------------------------------------------------------
FG_GETLINES
Prototype
int fg_getlines (void);
Description
The fg_getlines routine returns the number of text rows per video page
for the current video mode.
Parameters
none
Return value
The number of text rows per video page for the current video mode.
Restrictions
none
See also
fg_setlines
Examples
3-5
------------------------------------------------------------------------------
FG_IMAGESIZ
Prototype
long fg_imagesiz (int width, int height);
Description
The fg_imagesiz routine determines the number of bytes required to store
a mode-specific bit-mapped image of specified dimensions.
Parameters
width specifies the image width in pixels.
height specifies the image height in pixels.
Return value
The number of bytes required to store a mode-specific bit-mapped image of
the specified size in the current video mode.
Restrictions
none
See also
fg_clpimage, fg_drwimage, fg_flpimage, fg_getimage, fg_revimage
Examples
9-20
------------------------------------------------------------------------------
FG_INITEMS
Prototype
int fg_initems (void);
Description
The fg_initems routine initializes expanded memory (EMS) for use with
Fastgraph.
Parameters
none
Return value
0 = success
-1 = Expanded Memory Manager not installed or not accessible
Restrictions
This routine requires an Expanded Memory Manager (EMM) that conforms to
the Lotus/Intel/Microsoft Expanded Memory Specification (LIM-EMS) version
3.2 or later. On 80386 and 80486 systems, the EMM386.EXE device driver
supplied with DOS 5.0 can be used to treat some or all of extended memory
as expanded memory.
The Expanded Memory Manager uses interrupt 67h. As a result, this vector
is not available for application programs.
See also
fg_allocems, fg_initxms
Examples
8-9
------------------------------------------------------------------------------
FG_INITXMS
Prototype
int fg_initxms (void);
Description
The fg_initxms routine initializes extended memory (XMS) for use with
Fastgraph.
Parameters
none
Return value
0 = success
-1 = XMS driver not installed or not accessible
Restrictions
This routine requires an external device driver that conforms to the
Lotus/Intel/Microsoft/AST eXtended Memory Specification (XMS) version
2.0, such as HIMEM.SYS. This driver requires an 80286, 80386, or 80486
system.
See also
fg_allocxms, fg_initems
Examples
8-9
------------------------------------------------------------------------------
FG_MAKEPCX
Prototype
int fg_makepcx (int minx, int maxx, int miny, int maxy, char *filename);
Description
The fg_makepcx routine creates a PCX file from the specified rectangular
region of the active video page. The region's extremes are expressed in
screen space units.
Parameters
minx is the x coordinate of the region's left edge. Its value is reduced
to a byte boundary if necessary.
maxx is the x coordinate of the region's right edge. It must be greater
than or equal to the value of minx.
miny is the y coordinate of the region's top edge.
maxy is the y coordinate of the region's bottom edge. It must be greater
than or equal to the value of miny.
filename is the name of the PCX file to create. A device and path name
may be included as part of the file name. The file name must be
terminated by a null character (that is, a zero byte). If an identically
named file already exists, it is overwritten.
Return value
0 = success
1 = file not created
Restrictions
The fg_makepcx routine has no effect in text video modes or in the
Hercules low-resolution graphics mode. Refer to the description of the
fg_disppcx routine for information about PCX file compatibility between
different video modes.
In the Tandy/PCjr 16-color graphics mode (mode 9) and the native EGA
graphics modes (modes 13 through 16), the palette registers are not
readable. Hence, fg_makepcx will use the default palette settings when
used in these video modes.
See also
fg_disppcx
Examples
9-15
------------------------------------------------------------------------------
FG_MAPRGB
Prototype
int fg_maprgb (int red, int green, int blue);
Description
The fg_maprgb routine maps six-bit red, green, and blue color components
into a suitable palette value for the current video mode. You can then
pass this value to the fg_palette routine.
Parameters
red, green, and blue respectively specify the color's red, green, and blue
components. These values must be between 0 and 63; increasing values
produce more intense colors.
Return value
The mode-specific palette value for the specified color components.
Restrictions
This routine is meaningful only in 16-color graphics video modes.
See also
fg_palette, fg_palettes, fg_setrgb
Examples
5-13
------------------------------------------------------------------------------
FG_RESIZE
Prototype
void fg_resize (int width, int height);
Description
The fg_resize routine changes the dimensions of a video page in EGA and
VGA graphics modes.
Parameters
width specifies the new video page width in pixels.
height specifies the new video page height in pixels.
Return value
none
Restrictions
The size of a video page is constrained only by the amount of memory on
your video adapter. Increasing the size of a video page proportionally
reduces the number of physical pages available. For example, increasing
the page size from 320 x 200 to 640 x 400 decreases the number of video
pages from 8 to 2.
When you call fg_resize, the visual page must be page 0.
If you have created any virtual or logical video pages, you must release
them with fg_freepage before calling fg_resize, and then create them
again afterward.
If you have initialized the mouse (with fg_mouseini), joysticks (with
fg_initjoy), expanded memory (with fg_initems), or extended memory (with
fg_initxms), you should call re-initialize these resources after calling
fg_resize. Most mouse drivers expect a fixed video page width, so the
mouse cursor may become distorted after resizing video pages.
The fg_setmode routine re-establishes the dimensions of a video page to
the default resolution for the selected video mode.
This routine is meaningful only in the native EGA graphics modes (13 to
16), native VGA graphics modes (17 and 18), and extended VGA graphics
modes (20 to 23). It has no effect in other video modes.
See also
fg_pan
Examples
8-10, 11-7
------------------------------------------------------------------------------
FG_RESUME
Prototype
void fg_resume (void);
Description
The fg_resume routine restarts asynchronous music previously suspended
by the fg_suspend routine. It has no effect if there is no suspended
music.
Parameters
none
Return value
none
Restrictions
none
See also
fg_musicb, fg_suspend
Examples
13-8
------------------------------------------------------------------------------
FG_SETDACS
Prototype
void fg_setdacs (int start, int count, char *values);
Description
The fg_setdacs routine defines the values of a block of contiguous video
DAC registers by specifying their red, green, and blue color components.
Defining many DAC registers with fg_setdacs is considerably faster than
doing so individually with fg_setrgb.
Parameters
start is the starting video DAC register number, between 0 and 255.
count is the number of contiguous DAC registers to define. If the
sum of start and count exceeds 255, the register numbers wrap around
and resume with register number 0.
values is the array containing the color components. The first three
bytes of this array must contain the red, green, and blue components
for DAC register start, the next three bytes contain the components for
register start+1, and so forth. The size of the values array must be at
least 3*count bytes.
Return value
none
Restrictions
This routine has no effect in text video modes, or in any graphics video
mode numbered 16 or below (because these video modes do not use DAC
registers).
See also
fg_getdacs, fg_getrgb, fg_setrgb
Examples
5-12
------------------------------------------------------------------------------
FG_SETLINES
Prototype
void fg_setlines (int lines);
Description
The fg_setlines routine extends an 80-column text mode to 25, 43, or 50
lines per screen. The fg_setmode routine sets the number of lines to 25
when establishing an 80-column text mode.
Parameters
lines is the number of text rows per screen. On EGA systems, the value
of lines must be 25 or 43. On MCGA systems, it must be 25 or 50. On VGA
systems, it must be 25, 43, or 50. Any other value is ignored. Before
calling fg_setlines, you should call fg_testmode with pages=0 to see if
the user's system supports the number of rows needed.
Return value
none
Restrictions
This routine is only meaningful when running in 80-column text modes on
EGA or VGA systems (in other cases it does nothing).
When you call fg_setlines, the visual page must be page 0.
Calling fg_setlines makes the text cursor visible.
If you have initialized the mouse (with fg_mouseini), joysticks (with
fg_initjoy), expanded memory (with fg_initems), or extended memory (with
fg_initxms), you should call re-initialize these resources after calling
fg_setlines.
See also
fg_getlines, fg_testmode
Examples
3-5
------------------------------------------------------------------------------
FG_SUSPEND
Prototype
void fg_suspend (void);
Description
The fg_suspend routine suspends asynchronous music previously started
by the fg_musicb routine. It has no effect if there is no asynchronous
music in progress.
Parameters
none
Return value
none
Restrictions
A program must not exit to DOS with music suspended. You must call
fg_hush to cancel the music first.
See also
fg_hush, fg_musicb, fg_resume
Examples
13-8
------------------------------------------------------------------------------
Optimizations and improvements to existing routines
------------------------------------------------------------------------------
In video modes that offer virtual pages, Fastgraph now allows up to 64 pages
instead of 16. Usually, the amount of RAM available on your system will
limit the number of virtual pages to a smaller number, however.
Video modes 20 and 21 are as much as 16 times faster than in Fastgraph
version 2.00 and 2.01. In fact, mode 20 is now three to four times faster
than mode 19.
Graphics in the native EGA and VGA modes (modes 13 to 18) are considerably
faster when the mouse is active.
The fg_clpimage and fg_flpimage routines no longer extend the clipping limits
to byte boundaries in the native EGA and VGA graphics modes. These routines
now clip to the exact limits specified in fg_setclip.
The fg_dispfile routine now displays any size pixel run file. Previously,
pixel run files were limited to 64K bytes.
The fg_freepage routine releases virtual pages or logical pages. Logical
pages may be in conventional memory, expanded memory (EMS), or extended
memory (XMS).
The fg_getmap routine in the large model libraries now works properly in
video modes 20 and 21.
The fg_rect and fg_clprect routines are nearly twice as fast in the native
EGA and VGA graphics modes than in previous versions.
The fg_tcxfer routine is over eight times faster in the native EGA and VGA
graphics modes than in previous versions.
The 640x480 VGA graphics modes (17 and 18) formerly offered one physical page
and no virtual pages. These modes now offer a partial second partial page
(page 1) containing 320 pixel rows. However, you cannot use the fg_setvpage
or the fg_text routines on the partial video page.
Fastgraph no longer uses interrupt 64h.
Other miscellaneous code optimizations have been applied to several Fastgraph
routines.
------------------------------------------------------------------------------
EDITSPR utility
------------------------------------------------------------------------------
The EDITSPR utility changes all pixel runs of one color to another color in
an image file stored in Fastgraph's standard pixel run (.SPR) format. The
syntax of the command for invoking the EDITSPR utility from the DOS command
prompt is
EDITSPR <input_file> <output_file>
where <input_file> is the name of the original image file, and <output_file>
is the name of the new image file. EDITSPR does not modify the <input_file>
in any way, but it will overwrite the <output_file> if an identically named
file exists in the current directory.
After it reads the pixel runs from the <input_file>, EDITSPR will perform the
requested color changes. It does this iteratively by asking for an old color
value followed by a new color value (each value must be between 0 and 255).
EDITSPR then finds the pixel runs of the old color value and changes them to
the new color value. Following this, EDITSPR displays a message stating how
many pixel runs it changed. This process repeats until you enter a negative
number for either color value.
EDITSPR will next combine adjacent pixel runs of like colors. For example,
suppose the original image file contained a color 1 pixel run of length 50,
followed by a color 2 pixel run of length 20, followed by another color 1
pixel run of length 10. If you changed all color 2 pixel runs to color 1,
EDITSPR will combine these three pixel runs into a single run of length 80.
Finally, EDITSPR will close the <output_file>.
------------------------------------------------------------------------------
GrabRGB utility
------------------------------------------------------------------------------
The GrabRGB utility is a terminate and stay resident program (TSR) to capture
the current red, green, and blue color components of video DAC registers in
the 256-color MCGA and VGA graphics modes. You can use GrabRGB together with
Fastgraph's SNAPSHOT utility to preserve the original colors of a captured
image (for more information on SNAPSHOT, see Appendix A of the "Fastgraph
User's Guide").
To load GrabRGB, just enter the command GRABRGB at the DOS prompt. After
GrabRGB loads, control returns to the DOS prompt. At this point, you can use
any method whatsoever to display a 256-color graphic image and then press the
Alt and right shift keys at the same time to capture the current DAC
settings. You don't need to load GrabRGB for each image, just once per
system boot. GrabRGB uses about 15,000 bytes of conventional memory once
loaded.
To illustrate the use of GrabRGB, suppose you have drawn and saved a
256-color image with a commercial paint program, and you want to incorporate
this image into a Fastgraph application. Once you load SNAPSHOT and GrabRGB,
activate the paint program and retrieve your image. Then press the Alt and
left shift keys to capture the image with SNAPSHOT. After SNAPSHOT's success
tone (three quick medium-pitched sounds), press Alt and right shift to
capture the RGB components of each DAC register with GrabRGB, and wait for
GrabRGB's success tone. Finally, exit the paint program and return to the
DOS prompt.
The sequence described in the preceding paragraph will write the RGB color
components for each DAC register to a file named GRABRGB.nnn in the current
directory. The file type "nnn" will be the first sequence of digits that
does not result in a duplicate file name. That is, if there are no GrabRGB
output files in the current directory, GrabRGB will use the file name
GRABRGB.000. The next time you use GrabRGB, it will store the RGB
information in GRABRGB.001, then GRABRGB.002, and so forth. If you rename or
delete one of these files, GrabRGB will again use that file name. For
example, if you delete GRABRGB.000 but keep GRABRGB.001, GrabRGB will next
use the file name GRABRGB.000.
If for some reason GrabRGB is unable to obtain the RGB components of each DAC
register, it will produce its error tone (a single low-pitched sound). The
most common cause of this is trying to capture an image from a text video
mode, or from a graphics video mode with fewer than 256 colors. It will also
occur if there is insufficient disk space or if all 1,000 output file names
are already being used.
Each line in the output file created by GrabRGB is of the form:
nnn,rr,gg,bb,
where "nnn" is a DAC register index (between 0 and 255), "rr" is the red
component of that DAC register, "gg" is the green component, and "bb" is the
blue component. Each color component is between 0 and 63. You can edit and
reformat these lines as necessary for inclusion in a C initializer list, a
QuickBASIC or FORTRAN data statement, or a Turbo Pascal array-type constant
list. Such an array of RGB components, but without the "nnn" indices, is in
the format expected by fg_getdacs.
By default, GrabRGB captures information for all 256 DAC registers. If you
want to consider only the DAC registers with color components different from
their original values, just include the /D option when you load GrabRGB
(that is, use the command GRABRGB /D). If you specify the /D option and all
256 DACs use their default values, the output file will contain a message
stating this.
------------------------------------------------------------------------------
HERCFIX utility
------------------------------------------------------------------------------
The HERCFIX utility allows you to use SNAPSHOT (and perhaps other TSRs) with
programs that do not update the BIOS data area when establishing the 720x348
Hercules graphics mode. If you use SNAPSHOT with such a program, SNAPSHOT
will think the monochrome text mode (video mode 7) is active and will produce
its low-pitched error tone when activated.
If this occurs, use HERCFIX to load the application from which you are trying
to capture the image. To do this, enter
HERCFIX <command>
at the DOS prompt, where <command> is the command line that activates the
application. For example, suppose you use the command line "PAINTER /H" to
run a commercial paint program in Hercules graphics mode. To load the paint
program with HERCFIX, you would enter the command "HERCFIX PAINTER /H".
For complete information about SNAPSHOT, please refer to Appendix A of the
Fastgraph User's Guide.